home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / serial / dim-1.000 / dim-1 / dim-1.03 / dim-1.03.txt < prev    next >
Text File  |  1994-01-26  |  21KB  |  511 lines
  1. ==========================================================================
  2.  
  3.                          Dial-in for Linux
  4.                          -----------------
  5.  
  6.                         using getty_ps 2.0.7b
  7.  
  8.                                  plus
  9.  
  10.                                dim 1.03
  11.  
  12.                               Frank Brokken
  13.                        e-mail: frank@icce.rug.nl
  14.  
  15. ==========================================================================
  16.  
  17.  
  18. 1.1. Copyright
  19. --------------
  20.  
  21. The GNU General Public Licence is used with this program. I assume it's
  22. well known. If not, mail me for further details.
  23.  
  24.     Frank Brokken                   e-mail: frank@icce.rug.nl
  25.     Westerhaven 16                  phone:  (+31) 50 63 36 88)
  26.     9718 AW Groningen                       (mo-vr, 9:00-17:00 MET)
  27.     The Netherlands
  28.     
  29. 1.2. Obtaining the dim program
  30. ------------------------------
  31.  
  32. The dim package, which is described in this document, is available at 
  33. beatrix.icce.rug.nl through anonymous ftp (directory pub/unix).  The program 
  34. is contained in a zip called dim.X.YY.tar.gz, where X.YY is the version 
  35. number.  This file is availabe as dim.txt and is also contained in the 
  36. archive.  
  37.  
  38. Also, dim has been uploaded to tsx-11.mit.edu and sunsite.unc.edu
  39.  
  40.  
  41.  
  42. 2. PREREQUISITES
  43. ----------------
  44.  
  45. There is a number of prerequisites before the dim scheme can be
  46. implemented.
  47.  
  48. 2.1. The modem
  49. --------------
  50.  
  51. First of all, the Linux box must be equipped with a modem which is capable 
  52. of answering the phone and of dialling out.  If you don't have a modem yet 
  53. for your Linux system, but are considering buying one, go for a Hayes 
  54. compatible modem.  The remainder of this document shows examples for this 
  55. type of modem.  
  56.  
  57. Second, the modem must of course be connected to a telephone. Make sure that 
  58. the modem functions properly: it may be a good idea to boot under DOS and 
  59. try to talk to your modem via a communications package.  E.g., supposing 
  60. that you have MSKERMIT (the MSDOS version of Kermit), try booting DOS, 
  61. starting mskermit, and typing: 
  62.  
  63.     set port com<X>         {this sets the COM2 (external modem) or COM4
  64.                              (internal modem) port}
  65.                             {alternatively, use:
  66.                              set port com<X> <port-address> <irq-nr>}
  67.     set baud <speed>        {this sets the modem speed}
  68.     c                       {this should connect to the modem}
  69.     at                      {this sends an attention signal to the modem}
  70.     OK                      {modem should respond: OK}
  71.     atdt 1234567            {this instructs your modem to dial (atd) using
  72.                              tones (t) the phone number 1234567,
  73.                              your modem should start dialling,
  74.                              use atdp for pulse dialling}
  75.     NO RESPONSE or BUSY     {modem response if the phone number is
  76.     or NO CARRIER            invalid or does not connect to a modem}
  77.         or
  78.     CONNECT <speed>         {modem response if the phone number leads to
  79.                              a modem}
  80.  
  81. 2.2. The modem under Linux
  82. --------------------------
  83.  
  84. The modem must function properly under Linux. The suggested modem device 
  85. names are: 
  86.  
  87.     /dev/ttyS1 and /dev/cua1        for an external modem, and
  88.     /dev/ttyS3 and /dev/cua3        for an internal modem.
  89.  
  90. You may need to create these devices, if you don't have them yet. The 
  91. details on this are in the SERIAL.FAQ.  In the remainder of this document, 
  92. /dev/ttyS3 will be used in the examples; however, you may need to change 
  93. this device name into /dev/ttyS1 when appropriate.  Also, you may need to 
  94. recompile your kernel with serial IO support.  Furthermore, you will need 
  95. the program setserial, version 2.02 or higher (ftp-able from 
  96. tsx.11.mit.edu).  The setserial program takes many parameters; such as, the 
  97. uart type of the modem.  E.g., I have the following line 
  98.  
  99.     /etc/setserial /dev/ttyS3 irq 5 uart 8250
  100.  
  101. in my boot-script /etc/rc.local. This defines the uart of the modem. I have 
  102. set the irq line of the modem to 5 using a dipswitch; I chose that number 
  103. because that's the only irq I have left (originally, it's the irq number of 
  104. the second parallel port).  
  105.  
  106. After configuring the modem for Linux, making sure that your kernel supports 
  107. serial IO, etc., try talking to it through kermit.  Use the above session 
  108. example to test the working.  Try calling out to a `real' system and test 
  109. the reliability of the connection.  
  110.  
  111. 2.3 Dial-in under Linux
  112. -----------------------
  113.  
  114. Before you attempt to construct the dim procedure, you must make sure 
  115. that dialling in to your Linux system works.  For the dial-in you need the 
  116. `new' getty or uugetty: getty_ps version 2.0.7b or higher.  The sources for 
  117. getty_ps can be obtained at, e.g., tsx-11.mit.edu.  
  118.  
  119. 2.3.1. getty_ps
  120.  
  121. When constructing the new getty program, follow the instructions closely.  
  122. Make sure NOT do do a "make install" right away: first, do a "make" and test 
  123. the new getty as suggested.  A "make install" with a non-working getty
  124. will overwrite the previous (working) version, and you might not be able to
  125. login again on your linux-box for a while...
  126.  
  127. Once you have the new getty working and installed as 
  128. etc/getty, adapt the following files to get dial-in working:
  129. /etc/inittab, /etc/gettydefs, /etc/default/getty.ttyS3 (the ttyS3 again 
  130. referring to an internal modem; for an external modem, use ttyS1).  The 
  131. modifications for these files are described in the getty_ps documentation 
  132. and are illustrated below.  
  133.  
  134. 2.3.2. /etc/inittab
  135.  
  136. Here is a sample from my file inittab (see also the directory examples):
  137.  
  138.     s3:6:respawn:/etc/getty ttyS3 modem vt100
  139.  
  140. This line instructs init, the first program which is run under Linux, to 
  141. execute /etc/getty upon startup.  That program, getty, will then
  142. watch /dev/ttyS3 for activity.  When eventually the modem accepts a call,
  143. getty will try to establish a connection according to two files: 
  144. /etc/gettydefs and /etc/default/getty.ttyS3.  The specification "respawn" in 
  145. this line causes init to restart the getty process when it dies or when its 
  146. subprocesses die.  
  147.  
  148. 2.3.3. /etc/gettydefs
  149.  
  150. The file /etc/gettydefs defines the type of connection to establish. Here is 
  151. a part of my /etc/gettydefs: 
  152.  
  153.     #label  # connection definitions                # prompt    #next
  154.     #-----------------------------------------------------------------
  155.     modem   # B2400 CS8     # B2400 SANE -ISTRIP    #login:     # modem
  156.  
  157. Once getty detects activity on the specified input line, it will search 
  158. for the label "modem" (as mentioned in /etc/inittab) in its definition file 
  159. /etc/gettydefs.  That label occurs here, and instructs getty to try to 
  160. establish a 2400 baud connection. In my case, this is a fixed baud rate,
  161. you might want to change that if you want to use an adaptable baud rate
  162. setting. See the SERIAL-FAQ for details.
  163.  
  164. 2.3.4. /etc/default/getty.ttyS3
  165.  
  166. The file /etc/default/getty.ttyS3 is needed for the `new' getty program.  
  167. The previous getty, often still distributed with SLS, does not use this 
  168. file.  The file therefore has to be created.  Here is a sample of the file 
  169. /etc/default/getty.ttyS3: 
  170.  
  171.     SYSTEM=<name-of-your-linux-box>
  172.     VERSION=/proc/version
  173.     LOGIN=/bin/login
  174.     ISSUE=/etc/issue
  175.     CLEAR=NO
  176.     HANGUP=YES
  177.     INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK
  178.     TIMEOUT=60
  179.     CONNECT="" CONNECT
  180.  
  181. This file defines the following actions:
  182.  
  183.     (a) The first four lines define text information, to be displayed during 
  184.     the login process.  Refer to the getty_ps information for the meaning of 
  185.     these lines; e.g., the line LOGIN=/bin/login defines the program which 
  186.     is used to log in a user.  
  187.  
  188.     (b) The lines CLEAR=NO and HANGUP=YES define the way that getty 
  189.     handles the modem.  
  190.  
  191.     (c) The line
  192.  
  193.         INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK
  194.  
  195.     consists of strings, which are in turn either expected by getty to be read
  196.     from the modem line, or which are sent to the modem.  The INIT label 
  197.     tells getty to execute this sequence upon startup.     
  198.  
  199.     The sequence can be read as follows:
  200.  
  201.         - Getty should wait for no special string on the modem line ("").
  202.         - Getty should then send the string "ATH", followed by a
  203.           carriage-return, to the modem. This hangs up the phone line.
  204.         - Getty should then wait for the string OK to appear on the modem
  205.           line; that is the modem's response.
  206.         - Getty should then send "ATZ", followed by a carriage-return. This
  207.           re-initializes the modem.
  208.         - Getty should then wait for an OK.
  209.     - Getty will then send "ATS0=1", followed by a carriage-return. This
  210.       will instruct the modem to answer the phone on the first incoming
  211.       ring.
  212.           &C1 sets the carrier detect signal only when the remote carrier is
  213.           present.
  214.       &D3 forces a hangup of the line, and resets the modem, after an
  215.           ON-to-OFF Data Terminal Ready transition.  
  216.       &W writes the active configuration in the profile to be used by
  217.           default. (&W0&W1 would store the active profile in both
  218.           nonvolatile profile memories, that would be ok too).
  219.  
  220.       The &C1&D3 were added after experiencing problems with the modem
  221.           configuration after switching off the computer (in my case: the
  222.           modem too, as it's an internal one).  Apparently the &C1&D3
  223.           settings weren't kept, causing the modem to spawn login
  224.           constantly. The &C1&D3 addition cured the problem.
  225.  
  226.     - Getty should again wait for an OK from the modem. 
  227.  
  228.     Please note that the AT commands, which are sent to the modem, apply to 
  229.     my `Hayes-compatible' modem. Be sure to check your modem 
  230.     documentation for the exact syntax applying to your modem when using 
  231.     these commands for your own setup.  
  232.  
  233.     (d) The TIMEOUT specification instructs getty to break the connection 
  234.     when the user waits longer than 60 seconds before logging in.  
  235.  
  236.     (f) The line
  237.  
  238.         CONNECT="" CONNECT
  239.  
  240.     defines a chat-sequence to be performed after the modem has auto-answered
  241.     the phone. The sequence can be read as follows: 
  242.  
  243.         - Getty is instructed not to wait for specific information ("").
  244.         - Then getty waits for the string CONNECT, whereupon the login
  245.           process starts.
  246.  
  247. 2.3.5. The modem-setup itself
  248. -----------------------------
  249.  
  250. The modem itself should be configured as follows:
  251.  
  252. (profile 1 is identical to profile 0: I left it out. No phone-numbers are
  253. configured, also left out).
  254.  
  255. ----------------------------------------------------------------------
  256. ACTIVE PROFILE:
  257. B1 E1 L3 M3 Q0 V1 X4 Y1 &C1 &D3 &G0 &J1 &L0 &P1 &Q0 &R1 &S1 &X0 &Y0
  258. S00:000 S01:000 S02:043 S03:013 S04:010 S05:008 S06:002 S07:030
  259. S08:002 S09:006 S10:014 S12:050 S14:AAH S16:00H S18:000 S21:FFH
  260. S22:FFH S23:17H S25:005 S26:001 S27:40H
  261.  
  262. STORED PROFILE 0:
  263. B1 E1 L3 M3 Q0 V1 X4 Y1 &C1 &D3 &G0 &J1 &L0 &P1 &Q0 &R1 &S1 &X0
  264. S00:000 S14:AAH S18:000 S21:FFH S22:FFH S23:17H S25:005 S26:001
  265. S27:40H
  266. ----------------------------------------------------------------------
  267.  
  268. Several things are worth noting:
  269.  
  270. 1. Contrary to the SERIAL-FAQ, the modem is *not* shut up at all: command
  271.    echoing is on (E1), and the modem sends responses (Q0). In fact, by shutting
  272.    up the modem I had a completely failing INIT chat-sequence in the original
  273.    setup, as getty never got anything back from the modem.
  274.  
  275. 2. &C1: Carrier Detect Signal is only ON when a remote carrier signal is
  276.    present. This is in line with the SERIAL-FAQ.
  277.  
  278. 3. &D3: Once the connection is broken (On to Off Data Terminal Ready
  279.    transition), the modem will hangup the line, reset, and return to
  280.    command-mode. Again, in line with the SERIAL-FAQ.
  281.  
  282.  
  283.  
  284.  
  285. After installing getty_ps and modifying all necessary files, you should have 
  286. the dial-in protocol established.  Test the dialling in before attempting 
  287. the next step: installing dim.
  288.  
  289.  
  290. 4. GETTY DEFINITION FILES
  291. -------------------------
  292.  
  293. Dim uses two getty definition files. These files 
  294. are /conf/callback/getty.ttyS3.org and /conf/callback/getty.ttyS3.dim.
  295.  
  296. (The directory specification 'conf/callback' is a leftover from Karel
  297. Kubat's callback system. His directory slection has been accepted unaltered
  298. by dim. It can of course be changed to another name of your liking).
  299.  
  300. The first of these files, with the extension .org, is the file which causes 
  301. getty to accept incoming calls.  This file is used in dim's -reset command,
  302. and has already been described before:
  303.  
  304.     SYSTEM=<name-of-your-linux-box>
  305.     VERSION=/proc/version
  306.     LOGIN=/bin/login
  307.     ISSUE=/etc/issue
  308.     CLEAR=NO
  309.     HANGUP=YES
  310.     INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK
  311.     TIMEOUT=60
  312.     CONNECT="" CONNECT
  313.  
  314.  
  315. The file /conf/callback/getty.ttyS3.dis will diable the autoanswering
  316. facility of the modem. It contains but one line:
  317.  
  318.     INIT="" ATH\r OK ATZ\r OK ATS0=0&C1&D3&W\r OK
  319.  
  320. Via this initialization the modem is instructed not to react to incoming calls.
  321. The command ATS0=0 disables the auto-answering.
  322.  
  323. 5. INSTALLING DIM
  324. -----------------
  325.  
  326. Before unpacking the zip containing the sources, create an appropriate 
  327. directory (e.g., /usr/local/src/dim).  Move the archive to this 
  328. directory and unpack it.  Archives in the form .zip can be unpacked using 
  329. "unzip <archive>".
  330.  
  331. 5.1. The file src/config.h
  332. --------------------------
  333.  
  334. The pathnames used by the dim program use the directory /conf/callback.
  335. If you dislike this name, edit src/config.h and substitute your favorite 
  336. name.  Note however that it may be a good idea to place all configuration 
  337. files into a directory which is only readable by root.  In the following 
  338. discussion it is assumed that the default name /conf/callback is used.  
  339.  
  340. dim assumes that you are using an internal modem, pointed to by the 
  341. device /dev/ttyS3.  If you are using an external modem, change all 
  342. occurrences of "ttyS3" into "ttyS1" in the file src/config.h.  
  343.  
  344. Furthermore, you may want or need to change the following strings or defines
  345. in src/config.h:
  346.  
  347.     TMPGETTY - this filename is used as a temporary file. dim deletes 
  348.     this file after operation.  Default: /tmp/getty.ttyS3.tmp.  
  349.  
  350.     LOGIN - the original login program. Default: /bin/login.
  351.  
  352.     ERRLOG - the logfile where cblogin logs fatal errors. Default:
  353.     /usr/adm/dim.log.
  354.  
  355.     PANICLOG - the file where cblogin writes fatal errors, when ERRLOG 
  356.     cannot be written.  Default: /dev/console.  
  357.  
  358.     EMAIL - e-mail address which is displayed to the dialling in user when 
  359.     cblogin cannot proceed.  You can leave this string undefined if you do 
  360.     not wish any e-mail address shown.  The default is my e-mail address; 
  361.     please change the string or undefine it, or my name will appear in your 
  362.     modem's login screen.
  363.  
  364.     DISABLEGETTY - Define this filename if you want the system 
  365.     administrator's tool cbstat to be able to disable the modem. This file 
  366.     must then contain a getty definition which disables the modem.
  367.     
  368. 5.2. Building dim
  369. -----------------
  370.  
  371. First, create the directory for the configuration files of dim. E.g., 
  372. if this directory should be the default conf/callback, do a: 
  373.  
  374.     mkdir -p /conf/callback
  375.     (cd /conf; chmod 700 dim)
  376.  
  377. This will make the directory readable by root only.
  378.  
  379. If you have Icmake, look at the file "build". Modify the define dimDIR 
  380. (default: /conf/callback) if you do not want to use this name as the basic 
  381. dim directory.  Modify the define BINDIR if you wish an 
  382. installation of this program into an other directory.  After modifying the 
  383. file "build", do a "./build install".
  384.  
  385. If you do not have Icmake, get it. Icmake is a powerful program maintenance 
  386. tool and a script language, and is available at tsx-11.mit.edu (directory 
  387. pub/linux/sources/usr.bin) or at beatrix.icce.rug.nl (directory pub/unix).  
  388. The file icmake.doc explains how to install Icmake.  If you cannot get 
  389. Icmake, chdir to the directory src and do: 
  390.  
  391.     (cd dim ; gcc -c *.c)
  392.     gcc -o dim/dim dim/*.o
  393.     mv dim/dim /usr/local/bin
  394.     chmod 700 /usr/local/bin/dim
  395.  
  396. Note that dim is only readable and executable by root.
  397.  
  398. 5.3. The program dim
  399. --------------------
  400.  
  401. The program dim, which is installed by default to /usr/local/bin, is a 
  402. small tool to either see what the dim setup is doing, or to force 
  403. the modem into auto answering mode or not.  
  404. The program should be readable and executable by root 
  405. only, since it is only an administrator's tool.  When dim is invoked
  406. without arguments, usage information is shown on the screen.  
  407.  
  408. The actions of dim are further discussed below:
  409.  
  410.     dim -disable: This option can only be used when the define 
  411.     DISABLEGETTY is used during the compilation and installation of the 
  412.     package. The file /conf/callback/getty.ttyS3.dis is copied to 
  413.     /etc/default/getty.ttyS3: the disable-file should contain commands
  414.     to disable the modem. Having copied this file, getty (for the
  415.     modem-line) is killed, and is immediately restarted again by init,
  416.     using the new getty.ttyS3 file.
  417.     
  418.     dim -enable: This forces the modem into its auto-answer state.
  419.     The getty definition file which allows only dial-in, 
  420.     /conf/callback/getty.ttyS3.org, is copied to 
  421.     /etc/default/getty.ttyS3. Then getty is killed, immediately to be
  422.     restarted again, using the new getty.ttyS3, by init.
  423.     
  424.     dim -file: This shows the current getty definition file 
  425.     /etc/default/getty.ttyS3, stripped of comment lines etc.  
  426.  
  427.     dim -wake: This tries to wake up init by sending a SIGHUP. This will
  428.     also generate a kernel message: '/etc/initrunlvl not found', which
  429.     may safely be ignored. The message is logged on the file
  430.     /usr/adm/syslog (i.e., on my linux-box)
  431.  
  432. 6. DIM AND CALLBACK
  433. -------------------
  434.  
  435. Karel Kubat's callback program and dim resemble each other in many ways.
  436.  
  437. Questions regarding callback should be sent to karel@icce.rug.nl. 
  438. Questions regarding dim can be sent to me: frank@icce.rug.nl
  439.  
  440. 7. INCOMING CALLS
  441. -----------------
  442.  
  443. At some point in time, when dim is installed, you might want to answer an
  444. incoming call via the modem, rather than via getty. I had some problems 
  445. initially in getting that part of the story running smoothly. 
  446. Here's how I do it now:
  447.  
  448.        - When you know an incoming call is about to arrive, start kermit.
  449.        - Then, if the call arrives, kermit rather than getty will catch
  450.          the call.
  451.        - The modem beeps and shreeks and falls silent. *THAT* is the 
  452.          time to enter:
  453.        - c
  454.        - Now you're connected to the incoming call via kermit, and you
  455.          can, e.g., login.
  456.      
  457. However, if you know there may be incoming calls but you don't want to
  458. accept them, then you will probably have given the command
  459.  
  460.                 dim -disable
  461.  
  462. Why would you do that? Well, I have my linux-box at the office call my
  463. linux-box at home every evening between 18:00 and 20:00, every 15". 
  464. Usually within that time-block I want to login at the office's linux-box.
  465. Not every 15", so I don't want the modem to accept the call at that time.
  466.  
  467. But, if the modem has been switched off (dim -disable) I can start kermit
  468. allright, but it won't take the call since the modem was switched off. This 
  469. is cured by the following 'modem.kermrc' file which I pass to kermit when
  470. kermit is started, i.e., I give the command
  471.  
  472.                 kermit modem.kermrc
  473.  
  474. The modem.kermrc file contains:
  475.  
  476.         ----------------------------------------
  477.         set line /dev/ttyS3
  478.         set speed 2400
  479.         set modem hayes
  480.         set dial dial-command ATDT%s\{13}
  481.  
  482.         set prompt [modem] kermit> 
  483.         
  484.         set file type bin
  485.         set file name lit
  486.  
  487.         output ats0=1\13
  488.         ----------------------------------------
  489.     
  490. The last line here is the interesting one: it enables auto-answering
  491. when kermit is started. So, if dim -disable has been given, I can start
  492. kermit and the modem will now accept incoming calls, due to the enabling
  493. of the auto-answering. Note that when kermit is done, it resets the modem 
  494. again, which may or may not what you want. 
  495.  
  496. At some point you might want to do an explicit dim -enable after the kermit 
  497. session.
  498.  
  499.      
  500. 8. HISTORY
  501. ----------
  502.  
  503. 1.00: Initial release. One program, dim, documentation, and example files.
  504. 1.01: Appending &C1&D3&W to the INIT chat-sequences to prevent constantly
  505.       respawning of login.
  506. 1.02: Change in the description only. A section on answering incoming calls
  507. 1.03: Changes in the description and file organization, related to 
  508.       sunsite and tsx-11 uploads. Icmake binaries are part of the
  509.       distribution.
  510.  
  511.